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PREFACE 

MANUAL OBJECTIVES AND READER ASSUMPTIONS 

The information presented in this guide enables a new user of RSX-1 IM 
to perform simple program development. The guide assumes a knowledge 
of computing in general, but it assumes no knowledge of the RSX-1 IM 
operating system. RSX-1 IM terms are defined when they appear for the 
first time. 

STRUCTURE OF THE DOCUMENT 

The guide has been structured so that the new user can learn terms and 
procedures as he or she actually creates and runs a program. The program 
development procedures are divided into three parts, corresponding to the 
following three chapters: 

• THE TERMINAL 

Chapter 1 discusses keyboard facilities, how to log onto the 
terminal, and how to issue commands to the operating system. 

• PROGRAM PREPARATION 

Chapter 2 describes how to use system programs to create, 
compile, hnk, and run a simple program. 

• THE FILES 

Chapter 3 describes how to specify and manipulate files. 

The development of a simple FORTRAN program that adds two numbers 
together is used as an example throughout the guide. The Appendix repro- 
duces the development of that program without the explanations provided 
in the previous chapters. 

ASSOQATED DOCUMENTS 

The guide makes frequent references to other RSX-1 IM documents, 
which are all described in the RSX-1 IMj RSX-1 IS Documentation 
Directory. The directory defines the intended readership of each 
manual in the RSX-1 lM/RSX-1 IS set and provides a brief synopsis 
of each manual's contents. 

DOCUMENTATION CONVENTIONS 

The following notes describe documentation conventions used in this 
guide. 

• Text in itahcs, other than document titles or section headings, 
indicates a new RSX-1 IM term. 

• Brackets ( [ ] ) indicate optional elements of command input 
(ABO[RT]), except when the brackets are a part of a User 
Identification Code ([300,221]). 
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In text that illustrates command format, upper-case letters ^ 

denote actual command input. Lower-case letters indicate ■ 

parameters that must be defined by the user. For example: 

ABO taskname 

The user types the letters ABO but must replace taskname with 
the name of an actual program. 

In examples of terminal dialogues, text in a contrasting color 
indicates user input, as opposed to computer-generated text 
shown in black. 
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A terminal provides the means of communication between you and the 
RSX-1 IM operating system. You instruct the system by typing commands 
at the terminal; the system either responds as instructed or displays an 
error message telling you that it does not understand or cannot respond 
to your input. 

RSX-1 IM supports a variety of terminals, which fall into two general 
categories: hard-copy terminals that print on paper, and Cathode Ray 
Tube (CRT) terminals that display characters on a screen. Most CRT 
terminals cannot provide a permanent record of terminal activity. 
Figure 1-1 illustrates a typical hard-copy terminal (an LA30 terminal 
in this photograph). Figure 1-2 at the top of the next page illustrates 
a typical CRT terminal (a VT50 terminal). 
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Figure 1-1 An LA30 Hard-Copy Terminal 



1-1 



The Terminal 




c 



c 



Figure 1 -2 A VT5 C RT Terminal 

1.1 USING A TERMINAL 

All terminals have a keyboard that has the same basic configuration as 
a typewriter. In addition, the keyboard includes other special keys that 
enable you to execute various computer functions. Individual keys are not 
always in the same position on different types of terminals, so check the 
keyboard layout each time you use a different terminal for the first time. 
Figure 1-3 shows the keyboard of an LA30 terminal. Figure 1-4 on the 
next page shows the keyboard of a VT50 terminal, which has a keyboard 
layout different from that of the LA30 terminal. 




Figure 1-3 Keyboard of an LA30 Terminal 
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Figure 1-4 Keyboard of a VT50 Terminal 

1.1.1 Function Keys 

Important function keys that appear on the terminals are described in 
Table 1-1. 
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Function Key 


Description 


CRor 
RETURN 


Terminates an input line and advances the carriage 
or cursor to position 1 of the next line. 


CTRL 


Is part of numerous 2-key combinations (CTRL and 
a letter key) that perform a variety of functions. 
Each vahd combination is called a control character, 
represented in this manual by CTRL/X, where X is 
the variable letter. 

The control characters you need to use most often 
are described in Section 1.1.2. 


RUBOUT 

or 

DEL 


Deletes the last character typed on the current hne, 
and contiguous characters to the left if you press the 
key repeatedly. Some CRT terminals erase each 
deleted character from the screen and move the 
printing position back one space. Otherwise, the 
terminal prints a backslash (\), then each deleted 
character, then another backslash before it 
prints the first correct character (for example, 
MISTKAE\EAK\AKE). 


TAB 


Advances the printing position to the next tab stop. 
Tab stops occur after every eighth character position 
in the line. 



1 . 1 .2 Control Characters 

A control character is entered by striking the appropriate letter while 
pressing CTRL. The system responds to some control characters by dis- 
playing an up arrow (t) followed by the appropriate letter (tU, for 
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example). Other control characters are not echoed in a display. See 
Section 2.1.1 in the RSX-llM Operator's Procedures Manual for a com- 
plete list of the control characters. The list in Table 1-2 describes those 
most commonly used. 



Table 1-2 Control Characters 



Character 



CTRL/C 



CTRL/0 



CTRL/Q 

and 

CTRL/S 



CTRL/R 



Description 



Gains the attention of the Monitor Console Routine 
(MCR), which interprets commands to the operating 
system. (See Sections 2.1.1 and 2.1.3.3 in the 
RSX-llM Operator's Procedures Manual for more 
information about the use of CTRL/C.) In most 
cases the system responds to CTRL/C by displaying 
the prompt 

MCR> 



Alternately discards and resumes the display of 
output sent to the terminal. Discarded output is 
lost. 

For example, if you are running a program that 
generates unwanted output, type CTRL/0. The 
system then discards that program's output until 
you type CTRL/0 again. (Note that the only pro- 
gram affected is the one sending output to your 
terminal when you type CTRL/O.) 

See the RSX-llM Operator's Procedures Manual 
for a more detailed description of the CTRL/0 
function. 



CTRL/S delays the display of further output until 
you type CTRL/Q to restart it. For example, if you 
are using a CRT terminal that displays output too 
quickly to be read easily, press CTRL/S to halt the 
display; then, when you have read the screen, press 
CTRL/Q to restart the output display. Repeat the 
process as necessary. 



Performs a carriage return and retypes the current 
line, omitting any deleted characters. If the 
DELETE or RUBOUT key on your terminal prints 
backslashes and deleted characters, the current line 
may be difficult to read because it contains 
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Table 1-2 (Cont.) Control Characters 
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Character 


Description 




numerous extraneous characters. Before terminating 
the Hne, type CTRL/R to ensure that you have 
made the right corrections. For example: 

MISTKAE\EAK\AKE <CTRL/R> 

MISTAKE 


CTRL/U 


Deletes the current line and performs a carriage 
return. This function allows you to retype a line 
when individual deletions would be impractical. 
Remember to type CTRL/U before you terminate 
the incorrect line. 


CTRL/Z 


Used by many tasks as a signal to exit and return 
control to MCR. 



1 .2 MCR COMMANDS 

The commands that control system operation from a terminal are called 
MCR commands. MCR stands for the Monitor Console Routine, which 
interprets terminal input. You communicate with MCR by entering a 
command string in the following format: 

command-name parameter(s)/keyword(s) line-terminator 



where: 



command-name 



consists of 3 or more letters, terminated by a space, 
that uniquely identify an MCR function. MCR reads 
the first 3 letters only; further letters merely help you 
to identify the command. Some examples of com- 
mand names are given below. (Brackets enclose 
optional input.) 



Names 



Function 



ABO[RT] ABOrt a running program (that is, 

stop it from running). 

DM0 [ UNT ] DisMOunt a volume . 

UFD Create a User File Directory (see 

Section 3.1.2). 
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/keyword 



usually specifies the object of the command function, 
which is most often a task or a device. (A task is an 
executable program.) One or more blank spaces must 
separate the parameter from the command name, and 
one parameter from another. For example, when you 
issue the Abort (ABO) command, you include the 
name of the running task to be aborted. 



ABO TASK 

Abort the task named TASK. 

RUN TASK 12:35:00 

Run the executable program 

12:35:00. 



called TASK at 



modifies either a parameter or the function of the 
command. A keyword consists of a slash (/) and an 
alphanumeric string indentification, optionally fol- 
lowed by an equal sign (=) and a keyword value : 

/keyword [ =value ] 

A keyword immediately follows the parameter it 
defines: 

parameter/keyword [=value] 

However, when a keyword modifies a command func- 
tion, you must insert at least one space between the 
name and the keyword: 

command-name /keyword [=value] 

Spaces are not required between consecutive 
keywords: 

parameter/keyword/keyword. . . 
command-name /keyword/keyword. . . 

Examples: 

• SET/CRT=TI: 

Enable backspace deletion on your CRT 
terminal. TI: always stands for the terminal you 
are currently using. The keyword /CRT deter- 
mines the function of the SET command. 

• ABO TASK/PMD 

Abort the task named TASK and produce a 
post-mortem dump, which is a listing that 
describes the state of the task when it was 
aborted. 
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line-terminator is either the CR or RETURN key, which performs a 
carriage return (<CR>), or the ALTmode or ESCape 
key (<ESO). Because <ESC> has special signifi- 
cance in cer^a^n circumstances ^hi^ manual u^e^ 
<CR> as a line terminator. 

When you press <CR>, the system sends the current 
hne to MCR. 

1 .2.1 Preparing to Issue Commands 

Before typing a command, you must ensure that the terminal is in the 
right state to receive input directed to MCR: 

• Check that the terminal's power is on. 

' • Check that the LOCAL/REMOTE switch is set to REMOTE. 

• Consult installation instructions for additional required terminal 
settings and dial-up instructions. 

• Press the CR or RETURN key to clear the terminal and to 
obtain the default prompt (>); or type CTRL/C to obtain the 
explicit MCR prompt (MCR>). 

Both the exphcit MCR prompt and the default prompt indicate that MCR 
can receive input typed at the terminal. Any other prompt indicates 
that the terminal will send the input to a task other than MCR. Both 
DIGITAL-supphed and user-written tasks can request input by displaying 
a task prompt at a terminal. If you see a task prompt, someone else is 
probably using that terminal. 

Examples in this manual use the default prompt, which a terminal displays 
most often when it is ready to receive input to MCR. 

NOTE 

If you are working with a system that does not 
support multiuser protection, you do not need 
to log on and off the terminal. Ignore the next 
two sections (1.2.2 and 1.2.3) and proceed 
directly to Section 1 .3 . 

1 .2.2 Logging On and Off a Terminal 

To begin a session at the terminal, you must issue the Hello command to 
log on. The logging-on procedure has several purposes: 

• It allows the system to ensure that you are an authorized user 
and to record information about your usage of the system. 

• It grants you the use of the terminal for access to the system 
until you log off. 

• It establishes initial defaults for your terminal activities. 
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The Hello Command 

Hello is an interactive command that prompts for its parameters, as 
follows: 



I 



>HELLO <CR> 
ACCOUNT OR NAME: 
PASSWORD: password 

where : 



user-id-code 
last-name 



<CR> 



user-id-code is a code, commonly called a UIC, that basically 

consists of two octal numbers that identify your 
account on the system. The first number (g) stands 
for your user group; the second number (m) is your 
own number within the group. The general UIC 
format encloses the two numbers, separated by a 
comma, in brackets: [g,m] . 

last-name is your last name, which you can enter instead of 

a UIC. The system derives the correct UIC from the 
name you specify. 

password is a 1- to 6-character alphanumeric string. The ac- 

count information maintained by the system includes 
the correct passwords for each UIC and last name. 
You cannot gain access to the system unless you 
type the password that corresponds to the UIC or 
name you have entered. 

So that your password remains private, the system 
does not print the characters you type in response 
to PASSWORD:. 

If you do not know your UIC or password, contact the system manager, 
or whoever controls the use of the system at your installation. 

Example: 

>HEL. <CR> 

account or name? charles <cr> 
password: grey <cr> 

RSX-llM BL18 MULT I -USER SYSTEM 

GOOD MORNING 

:32-MAY-77 :li:07 LOGGED ON TERMINAL TT4: 

22- MAY- 7 7 

SYSTEM WILL BE DOWN TODAY FROM 13:00-.t5:00 FOR 
CORRECT lUE MAINTENANCE 
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When the system receives the correct password, the terminal displays a 
logon greeting that includes a system identification and the date and 
time you logged onto the terminal. In addition, the terminal optionally 

Liiapitiya iLiiLiiCA in^a^a^\^:^, wmv^xi i*owa.±i_y ou.ppij' iiiHo/xiiia,i,j,\^ii lxxul c1i.i.\^^^li:> 

general use of the system. The default prompt (>) on a new hne after 
the messages indicates that you can proceed to issue further MCR 
commands. 

If the message 

HEL ~ OTHER USER LOGBED ON 

appears when you issue the Hello command, someone else is using the 
terminal. Either try to log onto a different terminal or seek out the person 
who logged on before you. Do not proceed to use the terminal yourself 
without the other user's knowledge. 

The Help Command 

Help is the only MCR command that you can issue before logging on. 
Because the first 3 letters are the same as Hello, you must enter HELP 
in full. When you issue this command, the terminal displays text (de- 
termined by each installation) that generally tells you how to log on and 
how to issue further commands. Even if you do not need help initially, 
issue the command at least once so that you know the nature of the 
information it provides. 

The Bye Command 

Whenever you finish a session, you must log off in order to make your 
terminal available to other users. Log off by typing 

>BYE <CR> 

This command has no parameters. The system responds by performing all 
actions required to terminate your activity at the terminal. (See the 
RSX-llM Operator's Procedures Manual for more details.) A message like 
the following then appears: 



HAVE A GOOD MORNING 

22-MAY-77 IXXZA TT4: LOGGED OFF 



You must reissue the Hello command to log on if you want to issue fur- 
ther commands other than Help. 

1 .2.3 The Quickest Ways to Log On 

Most users want to type as little as possible when using a terminal; they 
also want the quickest possible response time. This section describes 
ways to shorten the logging-on procedure. 
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Suppressing Optional System Messages 

Because the optional system messages that follow the Hello command 
greeting can sometimes be lengthy and usually need to be read only 
once a day, the Hello command allows you to enter a special form of 
the UIC parameter to suppress the display of these messages. The normal 
format for a UIC is [g,m] . However, to signal that you do not want to see 
the optional system messages, replace the comma with a slash (/), as 
follows: 

[g/m] 

In all, Hello permits four UIC representations: 

g/m 
[g/m] 
g,m 
[g,m] 

Either slash format always suppresses the optional messages. Brackets 
around the UIC are optional. Note, however, that a UIC must always be 
specified in the format [g,m] when it is not a parameter to the Hello 
command. 

If you have provided your name or the comma format of UIC, you can 
stop the message display by typing CTRL/0. The system then immedi- 
ately displays the default prompt. For example: 

>HEL <CR> 

ACCOUNT OR name: CHARLES <CR> 

PASSUORH: ::CR> 

RSX-llM BL18 MULTI-USER SYSTEM 

eOOn MORNING 

22-MAY- 77 12: 14 LOGGED ON TERMINAL TT4: 

22 ■HAY-77 

SYSTEM WILL BE DOW<CTRL/D> 



Suppressing ACCOUNT OR NAME: Prompt 

Another way to shorten the time it takes to log on is to enter the Hello 
command and UIC (or last name) on the same line: 

>HEL 201/312 <CR> 
PASSWORli: 



Entering the command in this way ehminates the need for the prompt 

ACCOUNT OR NAME :. j« 
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1.3 ERROR MESSAGES 

When MCR receives input that it does not recognize or knows to be 
incorrect or invalid, it displays an error message. An example is the 
message that appears if you try to log onto a terminal already being used 
by someone else (see The Hello Command in Section 1.2.2). Another 
message related to the Hello command can be returned if you enter a 
UlC (or last name) or password that is not stored in the system's account 
file: 

>HEL. <Cft> 

ACCOUNT OR name: peek <CR> 

password: JOHN <CR> 
HEL INVALID ACCOUNT 

y 

This attempt to log on is not successful either because the system does 
not recognize the last name (PEEK), or because JOHN is not the correct 
password. 

How you should react to an error condition depends on the message 
displayed. All error messages returned by MCR commands and MCR- 
related tasks are explained in the RSX-llM Operator's Procedures Manual. 
Individual command descriptions given in that manual include a list of 
possible error messages; Chapter 7 of that manual details all MCR error 
messages in alphabetical order. (Each error message displayed at your 
terminal begins with the 3-letter name of the associated command or 
task.) When you encounter an error while running a system task, such as 
a text editor, look for clarification in documentation that describes 
that software. 
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CHAPTER 2 
PROGRAM PREPARATION 



The steps required to prepare a program to run on RSX-1 IM are as 
follows: 



( 



1 . Create a source program. 

2. Compile or assemble the source program to produce object 
code. 

3. Link the object code to create an executable program, called a 
task. 

4. Issue an MCR command to run the task. 

Figure 2-1 illustrates this procedure in a diagram. Each of the steps in- 
volves the manipulation of a file, which is an owner-named area on a 
magnetic medium. This magnetic medium, called a volume, is used to 
store data. Disks, DECtapes, and ANS magnetic tapes are all volumes. 
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Figure 2-1 Steps in Creating a FORTRAN Task 



ANS magnetic tapes are tapes that conform to the American National Standard for 
Magnetic Tape Labels for Information Interchange, X3 .27-1969. 



2-1 



Program Preparation 



When you log onto a terminal, the system automatically allows you access 
to a disk; this disk is your default system disk, on which, unless you 
specify otherwise, the system stores all your files. (If your system does 
not support multiuser protection, you have automatic access to a system 
disk that is accessible to all users.) The following sections on program 
preparation assume you are using your default system disk. 

2.1 THE TEXT EDITOR (EDI) 

The RSX-1 IM Text Editor (EDI) is the system program used to create a 
source program file. 

2.1 .1 Creating a Source Program File 

To invoke EDI, issue a call to the editor in the same way that you issue an 

MCR command: 



>EDI <CR> 

The editor responds by displaying its task prompt: 

EDI> 

To create a file, you then specify a file name and a file type that describe 
the intended file contents in the following format: 



EDI>filename.type 
where: 



filename 
type 



is a 1- to 9-character alphanumeric string. 

is a 3-letter mnemonic, preceded by a period (.), related 
to the file contents. The following types are standard 
for programming language source files: 

Type Language 



BAS 


BASIC 


CBL 


COBOL 


FTN 


FORTRAN 


MAC 


MACRO 



To illustrate the creation of a source file, the following examples deal with 
a FORTRAN program called ADD. FTN, an interactive program that adds 
two numbers together and displays the result. 
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■^EDI <CR> 

EL LI I. > AriD.FTN <CR> 

CCREATINO NEW FILE3 

INPUT 
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When EDI receives the name of a file that does not exist, it creates an 
empty file with the given name and displays the last two lines shown in 
the example above. You can then immediately start to type in your source 

rwnavCKm WtiA-n i/r*ii tArmi«o+A ann\y lino r\€ ii-i«iif +Via circ+ii-rv^ of*-i.fae <+ ^•»^ "^ 
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buffer, which EDI subsequently writes to the new file. 

Use the keyboard facilities described in Tables 1-1 and 1-2 to correct any 
input mistakes on the current line. Once a line has been terminated and 
written to the file, you must use editor commands to correct it. 

The following example specifies the new file on the same line as the call to 
EDI; this format shows an alternate (and quicker) way to summon the 
editor to create a file (Note the use of the DELETE or RUBOUT key, 
CTRL/R, and CTRL/U). 

y£\Sl ADD.FTN <CR> 

L CREATING NEW FILE] 
INPUT 

TYPE 1 <CR> 

1 FORMAT (' ENTER TWO NUMBERS - M,N') <CR> 
APPE\EPP\CCEPT 2fKfL <CTRL/R> 

ACCEPT 2»KtL <CR> 

2 FORMAT (22\2\15) <CR> 
PRINT "U 

TYPE 3I.K+L <CR> 

3 FORMAT (' THE SUM IS ',15) <CR> 
STOP <CR> 

END <CR> 
-•::CR> 

*EX <CR> 
CEXII J 



Note the last four lines of the example above: 

<CR> 

t£X <CR> 
LEXIT] 



After terminating the last line in the program, type <CR> as the first 
character in the new line. EDI responds by displaying an asterisk (*) 
prompt. Until this point, EDI has been operating in input mode, entered 
automatically when EDI created the new file. Typing carriage return 
(<CR>) at the beginning of a new Hne switches EDI from input mode to 
edit mode; the asterisk is a prompt for editor commands. The command 
EX instructs EDI to close the file ADD.FTN and then to exit to MCR. 

2.1.2 Displaying a Copy of the New File 

To display a copy of the new file, issue the command 

>PIP Ti:=ADD,FTN <CR> 
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This command requests the Peripheral Interchange Program (PIP) to dis- 
play a copy of ADD.FTN at your terminal. TI: (Terminal Input) is a 
device name that always represents the issuing terminal. (See Chapter 3 
for more information about PIP.) When entering this PIP command, re- 
member to type an equal sign (=) between TI: and the name of the file to 
be copied : 

>PIP TI:=filename.type <CR> 

Example: 

>PIP Ti:=AnD.FTN <CR> 

TYPE 1 

1 FORMAT (' ENTER TWO NUMBERS - M»N') 
ACCEPT 2I.K+L 

2 FORMAT (215) 
TYPE 3fK+L 

3 FORMAT (' THE SUM IS 'fI5) 
STOP 

END 



I 



I 



c 



2.1 .3 Editing a Source Program File 

To edit an existing file, enter the EDI command: 

>EDI ADD.FTN <CR> 

Note that this is the same command line entered to create the file 
ADD.FTN. However, because ADD.FTN now exists, EDI responds 
differently: 

>F-D]: ADD.FTN <CR> 
C00009 LINES READ IN3 
CPAGE 12 
* 

EDI retrieves the existing file and automatically enters edit mode, indi- 
cated by the messages and the asterisk prompt. The message [00009 
LINES READ IN] tells you the number of lines from the input file that 
EDI has read into a buffer. The lines within the buffer comprise the cur- 
rent block of text to be edited (initially [PAGEl]). The buffer may or 
may not contain the complete input file depending on the sizes of the 
file and the buffer. To access text beyond the current block, you issue an 
editor command (Renew, see Table 2-1) that writes the current block to 
the output file and refills the buffer with the next block of text. 

An internal line pointer determines the line within the block to be edited. 

When EDI reads in a buffer, the line pointer points to a line immediately 

preceding the first line of text, thus allowing you to insert one or more 

lines at the top. You subsequently position the pointer by searching for a ^ 

particular piece of text or by using commands that reposition the pointer. ■ 
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Locating and Changing Text 

Most EDI Commands can be abbreviated to one or more letters. In the 
following text, the optional portion of each command is underlined. 

The example below illustrates the following editor commands: 

Command Function 

L OCATE Locate a string of text in the current block. 

C HANGE Replace one text string with another. 

N EXT Advance the line pointer to the next line. 

P RINT Print the current line. 

T OP Position the line pointer at the top of the current 

block. 

<CR> Point to and print the next line. 

Example: 

The text following each break in this example explains the command that 
has just been given to the editor. 

"EDI ADD.FTN <CR> 
C00009 LINES READ IN] 
CfAGE i: 
*L.OCATE ENTER <CR> 

Point to and print the hne containing the word ENTER. 

1. FORMAT (' ENTER TWO NUMBERS - MrN') 
*CHAN6E/ENTER/TYPE/ <CR> 

Change the word ENTER to TYPE. (Note how the slashes delimit both 
text strings.) EDI then prints the corrected hne. 

1 FORMAT (' TYPE TWO NUMBERS ~ MrN') 
*NEXT <CR.> 

Point to the next line. 

*PRINT <CR> 

Print the current line. 

ACCEPT 2fK+L 
^LOCATE SUM <CR> 
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Point to and print the line containing the word SUM. 

3 FORMAT (' THE SUM IS ',15) 

))(CHANGE/SUM/RESULT/ <CR> 

Change SUM to RESULT. 

3 FORMAT (' THE RESULT IS ',15) 

)»:LOCATE (215) <CR> 

Point to the line containing (215). 

C*E0B*3 

EDI reached end of buffer (EOB) without finding the text (215). The line 
pointer only moves forward through the buffer in response to a LOCATE 
command. 

))(TOP <CR> 

Move the line pointer to the top of the buffer (one line before the first 
line of text). 

#<CR> 

TYPE 1 

f 

Pressing carriage return in response to the * prompt instructs EDI to print 
the next line, which becomes the current line for editing. In this case, the 
next line is the first line in the buffer. 

(((EXIT <CR> 
CEXITI] 

Write the current buffer and the remainder of the input file to the output ■ 

file, close both files, and exit to MCR. 

Inserting and Deleting Text 

This section illustrates how to use the following additional editor com- 
mands. Again, the optional portion of each command is underlined. 

Command Function 

I NSERT Insert one or more new lines of text. 

ADD Append text to an existing line. 

DELETE Delete the current line. 

<ESC> Point to and print the previous line. ■ 
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Command Function 

R ETYPE Replace the current line with a new string of text. 

L IST Display at the terminal all lines remaining in the 

buffer, beginning with the current hne. Note that 
the line pointer does not move. 

Example: 

The text following each break in this example explains the command that 
has just been given to the editor. 

>Eni ADn.FTN <CR> 

EDI retrieves the latest edited version of ADD.FTN. 



1:000093 LINES READ IN 

CPAGE 1: 

* I INSERT <CR> 



Switch to input mode. Insert the following line immediately before the 
first line of text in the buffer. 

C THIS PROGRAM ADDS TWO NUMBERS TOGETHER <CR> 

<t;R> 

ileLOCATE NUMBERS <CR> 

i FORMAT (' TYPE TWO NUMBERS - MrN') 

)kAdd ! input PROMPT ■••;:c;r> 

Append comment text to current line. 

!)(PRINT <cr> 

1 format (' type two numbers - mrn')!input prompt 

>kLocate result <cr> 

3 format (' the result is '»i5) 

jkDELETE <cr> 
Delete the current line and move the pointer forward one line. 

,|!<EBC> 

Typing <ESC> in response to the * prompt instructs EDI to point to and 
print the previous line. 

TYPE 3fK+L 
^INSERT <CR> 



Enter input mode. 

■3 FORMAT (' THE SUM IS ' r 15) ! DISPLAY RESULT <CR> 
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Insert this new line of text. 

■:XF;;> 
Re-enter edit mode. 

*rop <CR> 
Reposition the line pointer at the top of the buffer. 

*<CR> 
Point to and print the next line, which is the first line in the buffer. 

C THIS PROGRAM ADDS TWO NUMBERS TOGETHER 

*RETYPE C ADD DISPLAYS THE SUM OF TWO NUMBERS <CR> 

Replace the current line with the text entered after the RETYPE 
command. 

*LIST <CR> 
Display the remainder of the current block. 

C ADD DISPLAYS THE SUM OF TWO NUMBERS 

TYPE 1 

1 FORMAT (' TYPE TWO NUMBERS - M»N')!INPUT PROMPT 
ACCEPT 2rK?L 

2 FORMAT (215) 
TYPE 3fK+L 

3 FORMAT <' THE SUM IS ' rI5) ! DISPLAY RESULT 
STOP 

END 

*EXIT <CR> 
CEXITII 



2.1 .4 Basic EDI Commands 

Table 2-1 summarizes a basic set of EDI commands. This set provides you 
with all the functions you need for simple editing. See the RSX-11 Utili- 
ties Procedures Manual for a full specification of EDI. 

2.2 COMPILING A SIMPLE FORTRAN SOURCE PROGRAM 

Compilation is the process of translating an ASCII source program into a 
machine-readable object program. In the call to the FORTRAN compiler, 
you supply a file expression that specifies the source program as an input 
file and the object program as an output file. For example: 

>FOR ADD.OBJ=ADD.FTN 
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Table 2-1 Basic EDI Commands 



( 



( 



c 
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Command 


Command Format 


Description 


ADD 


Add string 


Append string to current line. 


BorroM 


Bottom 


Move the line pointer to the bot- 
tom of the current block. 


CHANGE 


Change /string]/ 
string2/ 


Replace string 1 with string2 in the 
current Hne. 


<CR> 


Carriage return 


Print the next line, make it the 
new current line; or exit from 
input mode. 


CTRL/Z 


tz 


Close the input and output files 
and terminate the editing session. 


DELETE 


Delete 


Delete the current line. 


<ESC> 


ESCape or ALTmode 


Point to and print the previous 
line. 


EXIT 


EXit 


Close the input and output files 
and terminate the editing session. 


INSERT 


Insert [string] 


Insert string on the next line or 
enter input mode if string is 
omitted. 


LOCATE 


Locate string 


Locate the first line containing 
string. The search stops at the end 
of the current block. 


NEXT 


Next 


Advance the line pointer to the 
next line. 


PRINT 


Print 


Print the current line. 


RENEW 


RENew 


Write the current block to the out- 
put file and read in a new block 
from the input file. 


RETYPE 


Retype string 


Replace the current line with 
string. 


TOP 


Top 


Move the Hne pointer to the top 
of the block. 
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This command string requests the FORTRAN compiler to compile the ^- 

source program called ADD.FTN to produce an object file called ■- 

ADD.OBJ. As the example file expression shows, you specify, from left 
to right, the output file (ADD.OBJ), an equal sign (=), then the input file 
(ADD.FTN). 

Because the FORTRAN compiler defaults the object type to OBJ and the 
source type to FTN, you can abbreviate the above command string to 

::.-FOR ADD=ADD 

By appending switches to the input and/or the output file specifications, 
you can make special compilation requests. See the IAS/RSX-11 
FORTRAN IV User's Guide or the FORTRAN IV-Plus User's Guide for 
a description of FORTRAN compiler switches. All the examples in this 
section assume you are using the compiler defaults. 



Requesting a Listing File 

In addition to translating a source program, the FORTRAN compiler can 
also supply a listing file on request. For example: 

:::FOR ADDrADri=ADD <CR> 

The second ADD in the output file list instructs the compiler to produce a 
listing file of the source program and the storage map. (The storage map 
lists all the symbolic names referred to in the program.) If the system sup- 
ports the line printer spooler, the listing file is automatically directed to 
the line printer. (See Section 3.2.5 for a definition of spooling.) However, 
if your system does not spool line printer output, the command shown 
above creates a file called ADD.LST, stored on your system disk. 

Note that you must insert a comma (,) between the object file name and 
the listing device name; in other words, the required format is 

>FOR object ,list=source 

To send- the Hsting file to your own terminal, issue the following com- 
mand string: 

>FOR ADDi.TII=ADD* 

You can also request the compiler to produce a source hsting of a program 
without creating an object file as well. To make such a request, simply 
omit the object file field in the file expression. For example: 

>FOR »Ti:^=Anri <cr> 



If your system does not spool the listing file by default, you can request a line printer 
listing of the source file by substituting LP: for TI:, that is, >FOR ADD,LP:=ADD. 
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Note that you must enter a comma (,) before the listing device; otherwise 
f the compiler interprets TI: as an object file name. 

If the message 

HCR — TASK NOT IN SYSTEM 

appears after you issue the FOR command, the FORTRAN compiler is 
not currently resident in the system. In this case, issue the command 

::-f:UN $FOR <CR> 

This command requests the system to load the FORTRAN compiler into 
memory and to activate it. The compiler responds by prompting 



( 



c 



c 



c 



FOR> 

You then enter the file expression in the format illustrated above. For 
example: 

>RUN *FOR <CR:;- 
FOR.>ADri f ftriri--=ADri <cr> 

FOR><CTRL/Z> 

After the compiler has completed your request, it displays its task prompt 
once more. Enter CTRL/Z to terminate the compiler and remove it from 
memory. Alternatively, you can enter a file expression to request another 
compilation and/or source listing. 

2.3 ASSEMBLING A SIMPLE MACRO SOURCE PROGRAM 

To assemble a MACRO source program, issue a command in the following 
format: 

>MAC object,list=source 

By appending switches to the input and/or the output file specifications, 
you can make special assembly requests. See the lAS/RSX-I I MACRO-11 
Reference Manual for a description of assembly switches. All the examples 
in this section assume you are using the assembly defaults. 

The Assembler defaults the object type to OBJ, the list type to LST, and 
the source type to MAC; therefore, the command 

?MAC ADD»ADD=ADD 

represents 

.:^-MAC ADD , OBJ . ADD . LST =ADD . HAC 
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The Assembler-generated listing includes an optional table of contents, an 
assembly listing, and a symbol table. To request a listing only, without an 
assembled object file, omit the object file name. For example: 

>MAC »AriD=ADD 

See Requesting a Listing File in Section 2.2 for further information about 
obtaining a listing file. 

Requesting a Nonresident Assembler 

If the MACRO Assembler is not resident in memory when you issue a 

MAC command, the system displays the message 

MCR — ■ TASK NOT IN SYSTEM 

To load and activate the Assembler, issue the following command: 

>RUN *MAC 
MAO 

Then enter a file expression in response to the following Assembler 
prompt: 

>RUN *MAC <CR.> 

MAO ADD f ADD=ADD <CR.> 

MAO-'t^TRL/Z;- 

When the Assembler prompts for further input, either enter a file expres- 
sion to request another compilation and/or source listing, or type CTRL/Z 
to terminate the Assembler. 

2.4 LINKING OBJECT PROGRAMS - THE TASK BUILDER 

The Task Builder is a system program that makes an executable program 
unit, called a task, from one or more object modules; it links the object 
modules, resolves any references to the system library, and produces a 
single task image. The task image resides on disk until you issue an MCR 
command to install and run it. 

The simplest form of Task Builder (TKB) command input is 

>TKB task-image=object 

where task-image, the output file, is the name given to the executable 
task; and object, the input file, is the name of a module produced by a 
compiler or assembler. For example: 

■::.TKB AniuTSK=ADD.OBJ <CR> 
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Because TKB defaults the output file type to TSK, and the input file type 
to OBJ, you can shorten the above command string to 

>TKH ADD=AriD <CR> 

2.4.1 Full TKB Command Line 

The format of a full TKB command line accommodates three output files 
and any number of input files. The three output files are as follows: 



( 



1 . The task image (name.TSK), which contains the executable task 
image 

2. A memory allocation file (name.MAP), which lists information 
about the size and location of components within the task 

3. A symbol definition file (name. STB), which contains informa- 
tion about the task's global symbol definitions 

The list of input files comprises the one or more object modules to be 
linked into a single task image. 

The format is 



c 



c 



^11 



>TKB task-image,map,symbol-def=input,... 

If you omit an output file at the beginning or middle of the output list, 
retain a comma in the file's place to specify a null field. On the right-hand 
side of the equal sign, use a comma to separate one input file from an- 
other. Table 2-2 illustrates all the possible requests for TKB output files. 

Table 2-2 TKB Output File Requests 



Command Line 


Requested Output Files 


>TKB ADD>-MAF>SY«BOL-Atiri 


All three output files 


>TKB »>SYMBOL=ADD 


Symbol definition only 


>TKH -MAPySYMBOL^ADD 


Memory allocation and symbol 
definition 


>TKB fMAP=ADD 


Memory allocation only 


>rKB Ai:iBi..SYMBOL=ACn 


Task image and symbol 
definition 


>TKB ABEU MAP-ADD 


Task image and memory 
allocation 


>TKB ADD=ADD 


Task image only 
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2.4.2 Simple Multiline Format 

A long list of input files can cause a TKB command line to exceed your 
terminal's maximum line length. If this is the case, invoke TKB in the 
following manner: 

>TKB <CR> 
rKB> 

When you terminate the line immediately after entering TKB, MCR acti- 
vates the Task Builder, which then prompts for input. TKB continues to 
display its prompt after each' line of input until it receives the terminating 
characters // in the first two character positions. For example, the single 
command line 

>TKB TASK,HAP»SYMB0L=INPUTlrINPUT2»INPUT3 <CR> 

can be entered as follows: 



>fKB <CR> 

TKB>TASK.MAP.SYMB0L=INPUT1 <CR> 
•rKB>iNPUT2»INPUT3 <CR> 
TKB>// <CR> 



2.4.3 Default Types 

The default types in the TKB command line are as follows: 

File Type 

Task image TSK 

Memory allocation MAP 

Symbol definition STB 

Input OBJ 

Therefore, by default, the command line 

>TKB AriD>ABDfAtiD=ABD 

represents 

>TKB ADD.TSK»AIiEi.MAPfADD.STB=ADD.OBJ 

2.4.4 Listing the Memory Allocation (MAP) File 

The memory allocation (also called map) file is an ASCII file that contains 
information about the size and location of components within the task. If 
your system supports the spooling option, TKB spools this file to the line 
printer by default. 

However, without the spooling option, TKB stores this file on your sys- 
tem disk. If you want a listing only of the map file, rather than a stored 
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disk image, insert the name of a listing device in the place of the map file 
name. For example: 



This command instructs TKB to list the file called ADD.MAP on the line 
printer and to store the files ADD.TSK and ADD. STB on your system 
disk. 

Note that the third output file is called SY:ADD rather than ADD. SY: 
is the device name for your system disk. You must prefix the name of the 
STB file with SY: because the preceding device name has changed the 
default device to LP:. The command 

>TKB ADD > LP : T ADn=ADD 

instructs TKB to list both the map and the symbol definition file on the 
line printer, even though the third output file does not specify LP:. 
Because the STB file is in machine-readable code rather than ASCII code, 
an STB listing is of little or no use to you. The effect of the LP: specifica- 
tion does not cross the equal sign ;=ADD still represents SY:ADD.OBJ. 

2.4.5 Task Builder Switches and Options 

The Task Builder includes a variety of switches and options that afford 
you additional control over the construction of a task image. These 
switches and options are described in th.Q,RSX-llM Task Builder Refer- 
ence Manual. 

2.5 RUNNING A TASK 

The goal of the procedures described so far is to produce a program unit, 
called a task, that can run on RSX-1 IM. Linking, the last step in the prep- 
aration sequence, has generated a task image file (ADD.TSK) stored on 
your system disk. To run the task, issue the MCR Run command, specify- 
ing ADD.TSK as a parameter: 

>RUN ADD <CR> 

(The Run command defaults the type to TSK.) This command instructs 
the system to perform the following functions: 

• Locate ADD.TSK on your system disk. 

• Load a copy of the task image into memory. 

• Execute the task. 

• Remove the memory-resident task when it has completed its 
run. 

The task image file remains on disk, ready to be run, until you explicitly 
delete it. 
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The following listing illustrates three consecutive runs of the FORTRAN 

program ADD. ■ 



>RUN ADD <CR> 

TYPE TWO NUMBERS - MfN 

7>3 <CR> 

THE SUM IS 10 

TT13 — STOP 

•RUN ADD <CR> 

TYPE TWO NUMBERS - MrN 

522.628 <CR> 
THE SUM IS 1150 
TTJ3 •-- STOP 



>RUN ADD <CR> 

TYPE TWO NUMBERS -MfN 



9rl6 <CR::- 

THE SUM IS 25 

TT13 — STOP 



Note that, at the completion of each run, the program displays the line 
TT13 -- STOP 

TT13 is a temporary name assigned to the task while it is running. The 
version of the Run command shown in these examples causes the system 
to name the task TTn, where n is the unit number of the requesting 
terminal. 

Figure 2-2 reviews the steps in creating the FORTRAN task ADD, show- 
ing the specific files created along the way. 
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Figure 2-2 Steps in Creating the FORTRAN Task ADD 
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CHAPTER 3 
THE FILES 



This chapter describes files and file handling in two parts. Section 3.1 
defines all the elements of a complete file specification. Section 3.2 
then explains how to use a system program to manipulate files. 

3.1 COMPLETE FILE SPECIFICATIONS 

The examples given in Chapters 1 and 2 have stressed the use of defaults 
in a command line. Defaults are useful to know because they allow you 
to type as Httle as necessary when providing input to the system. How- 
ever, there are many situations in which you must supply a complete 
file specification because defaults do not apply. Section 2.1.1, Creating 
a Source Program File, defines two fields of a file specification: the file 
name and the file type. The three additional fields required to complete a 
file specification are 

dev: The name of the device that holds the volume on which 

the file resides 

[g,m] A User Identification Code (UIC) that identifies the 
directory that hsts the file 

;n A number that differentiates among various versions of the 

same file 

The format of a complete file specification is 

dev : [g,m ] filename. type ;n 

Examples: 

MT1:[1 16,23] DATA.DAT;4 
DT: [203,204] TASK.TSK;1 
DK2:[34,63]CALC.MAP;2 

3.1.1 The Device Name 

The device name specifies the unit on which the file resides. The name 
consists of 2 alphabetic characters, an optional 1- or 2-digit octal unit 
number, followed by a colon (:). When the name does not include a unit 
number, the system assumes that the unit number is 0. Example device 
names and corresponding units are listed on the following page. 
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Name 

DK2: 
DTI: 
MT: 



Corresponding Unit 

RK05 disk, unit 2 

DECtape, unit 1 

TUlO magnetic tape, unit 



I 



The device name can specify either an actual physical unit, like the 
three listed above, or a pseudo device name, which corresponds to dif- 
ferent physical units, according to whoever enters the name. For example, 
the name TI: refers to the terminal at which you are entering input. 
Another pseudo device name is SY:, which corresponds to your default 
system disk. All the files you have created so far reside on SY:. 

Table 3-1 lists the names of commonly used devices. The letter n stands 
for unit number. There are different types of disks and magnetic tapes, 
which have correspondingly different device names. Ask someone at your 
installation which names you should use. See the RSX-llM Operator's 
Procedures Manual for a complete list of device names. 



Table 3-1 Commonly Used Device Names 



Device 


Name 


DECtape 


DTn: 


Disk 


DBn: 
DKn: 
DMn: 
DPn: 
DXn: 


Line Printer 


LPn: 


Magtape 


MMn: 
MTn: 


Pseudo input terminal 


TI: 


Terminal 


TTn: 


System default device 


SY: 



c 



< 



Because the names TI:, TT:, and LP: represent input and/or output de- 
vices, rather than storage media, they generally do not appear in a com- 
plete file specification. When you refer to one of these devices in a file 
expression, the device name stands alone. For example, the following com- 
mand sends a copy of ADD.FTN on your system disk to your terminal: 

■■:P:i:f TU~ftDD.KIN 
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3.1 .2 User File Directories (UFDs) 

When you logged on (see Section 1.2.2), you either directly or indirectly 
(through your last name) specified your UIC. This UIC identifies the 

manager made you an authorized user. This UFD is itself a file that hsts 
the names of all files in your area. The system cannot locate a file unless 
it knows the UFD in which it is listed. 

If your UIC is [203,125], the name of your default UFD is 
203125.D1R;1. However, when referring to a UFD within a file speci- 
fication, you must use the UIC format, namely [203,125]. 

Your default UFD is not the only directory you can access. On many 
occasions you may need to access files belonging to someone else. In this 
event, you can use an MCR command to change your default UFD 
(SET/UIC=[g,m] ; see the RSX-llM Operator's Procedures Manual), or 
you can explicitly specify a different UFD in a file specification. (Note 
that neither of these actions changes the UIC with which you logged on.) 

Suppose you need to obtain a copy at your terminal of a file 
(LABEL.MAC, for e.xample) listed in UFD [203 ,200 } : 

-.PIP Ti:=i:203r200:LABEL.MAC 



This command assumes that LABEL.MAC resides on your SY:. 

In a system that does not support multiuser protection, your default UFD 
corresponds to the UIC specified in the last SET /UIC=[g,m] command 
issued from your terminal. To obtain a display of the current default 
UFD, issue the command 

>SET /UIC <CR> 

The system responds as follows: 

UlC=[g,m] 
where [g,m] is the current default UFD. 

Restrictions on File Access 

The system does impose restrictions on access to UFDs and other files 
that belong to other users. Every file includes a protection mask that 
determines who can access the file and in what manner; when you attempt 
to access a file, the system checks your UIC against the file's protection 
mask. If the check fails, your attempted access fails; and the system 
returns an error message at your terminal. 
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For example, if you attempt to edit a file that prohibits access by your 
UIC, EDI displays the following message: 



EDI 



PRiyiLEGE yiOLATION 



See the RSX-llM Operator's Procedures Manual for a more detailed 
description of file protection. 

3.1.3 Version Numbers 

A version number is octal and in the range to 77777. When a file is 
created, the system assigns it a version number of 1. Subsequently, the 
system increments the version number by 1 each time a new version of 
the same file is created. The "same file" is one that has the same name 
and type and is listed in the same UFD on the same volume. 

For example, whenever you edit a file, EDI creates an output file to con- 
tain the edited file. The file specification that refers to the output file 
is identical to the input file specification, except that the version has been 
increased by 1 . 



Input File 



Output File 



FILE.FTN;1 




EDI 




FILE.FTN;2 







Recompilations of the same source file also produce files with the same 
specifications except for differing version numbers. For example, the 
command 



€ 



>FORADD=ADD 



results in the creation of a file called ADD.0BJ;1. If you repeat the com- 
mand, the resultant file is called ADD. OBJ ;2 since the file ADD.0BJ;1 
already exists. 



Input FUe 



© 



Output File 





FOR 




ADD.OBJ;! 







I 



Q Iadd.ftnT 



FOR 



ADD.OBJ ;2 



3 . 1 .4 File Specification Defaults 

Table 3-2 explains the defaults for each field of the file specification. 



"ii 
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Table 3-2 FUe Specification Defaults 



Field 


Default 


dev: 


SY: 


[g,m] 


The UIC with which you logged on, or a UIC deter- 
mined by the MCR command SET /UIC=[g,m] (see 
the RSX-llM Operator's Procedures Manual). 


filename 


No default. 


type 


Depends on the command string in which the file 
specification appears. 


version 


For input files, the highest existing version. 

For output files, the highest existing version plus 1. 

Note that some commands require an explicit version 
number. 



3.2 MANIPULATING FILES USING PIP 

In the process of creating, editing, compiling, and Unking your program, 
you have generated a number of disk files: 



The original source file (ADD.FTN;!) 

An edited version of the source file (ADD.FTN;2) 

An object file containing the compiled program (ADD.0BJ;1) 

A task image file containing linked object code (ADD.TSK;1) 

A memory-allocation file (ADD.MAP;1) 

A symbol-definition file (ADD.STB;1 ) 

Additional versions of the above files, if you have repeated any 

of the program preparation steps 



All of these files remain on SY:, taking up space, until you explicitly 
delete them. Once you have determined which file you need to keep, 
how do you eliminate those you do not want? 

The following sections describe how to use the Peripheral Interchange 
Program (PIP). This program allows you not only to delete obsolete files, 
but also to perform a variety of other file-manipulation functions. When 
you invoke PIP, it performs a specific function according to the param- 
eters you supply. (See the RSX-11 Utilities Procedures Manual for a 
complete description of PIP; this manual describes only a subset of 
PIP functions.) 
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3.2.1 Listing a UFD 

All the files you have created are listed in your UFD. The following PIP 

command displays that list at your terminal. ^' 

>PIP /LI <CR> 

/LI is the List switch, where a switch is a slash followed by 2 letters. The 
letters abbreviate, or otherwise identify, the switch's function. For ex- 
ample, /LI means "list"; /DE means "delete." 

If you plan to issue a series of PIP commands, you can invoke PIP as 
follows: 

>P1P <Cf<;> 
p:[P>/L I <CR> 



DIRECTORY DBO: L"301 » 3143 
25-MAY-77 14:48 



25-MAY~77 14 J 31 
20-MAY-77 14:32 
25~HAY-77 14:32 
25-MAY-77 14:32 
20-HAY-77 15:26 
25-HAY -77 14:33 
20-MAY-77 15:27 
20-MAY-77 15:28 



ACD,0BJ?2 


2. 


ADD.TSK51 


29. 


ADD, MAP ;i 


4, 


ADD, STB 51 


3. 


ADD,FTNfl 


1. 


ADD.TSK»3 


29, 


ADD.OBJfl 


2, 


ADD,TSK>2 


29, 



TOTAL OF 99./112. BLOCKS IN 8, FILES 
PIP> 



c 



After Usting the directory, PIP displays its task prompt and waits for 
further input. To terminate PIP, type CTRL/Z in response to the prompt 

pip::..<ctrl/z> ^ 

The PIP directory listing includes the following information: 

^^ The physical device unit on which the files are stored, and the 
UIC that owns the directory. The unit named is your SY : ; the 
UIC is your current UIC. 

^S The date and time you issued the PIP request. 

^B The name, type, and version number of each file. 

^9 The size of each file in blocks. A block is 5 1 2 bytes (256 words) 
long. 

I 
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g- ^H The letter C if the file is contiguous, that is, not split into 

^ physically separated sectors on the disk. 



( 



c 



c 



( 






The date and time each file was created. 

The cumulative size in blocks of all the files listed and the num- 
ber of blocks allocated for all the files. 



Figure 3-1 assigns the letters in the above list to the appropriate parts of a 
directory listing. 



DIRECTORY DBOJ C301 r 3143 
25-MAY-77 14:48 



ADD. OBJ? 2 


2. 


ADD.TSKf 1 


29. 


ADD. MAP 51 


4, 


ADD. STB fl 


3. 


ADD.FTNJl 


1. 


ADD.TSK5 3 


29. 


ADD. OBJ rl 


2. 


ADD . TSK J 2 


29. 



o 

o o o o 

25-MAY-77 14J31 

C 20-MAY-77 14 J 32 

25-MAY~77 14J32 

25~MAY-77 14 J 32 

20-MAY-77 15J26 

C 25-MAY-77 14533 

20-MAY--77 15:27 

C 20-MAY~77 15J28 

^^ TOTAL OF 99./112. BLOCKS IN 8. FILES 
Figure 3-1 Sample Directory Listing 

PIP also accepts switches that request either fewer or more details about 
the files listed; these switches are described in ih^ RSX-11 Utilities Pro- 
cedures Manual. 

3.2.2 Listing Specific File Information 

PIP also allows you to obtain information about one file or a specific 
group of files. For example, if you want to see how many versions of 
ADD .TSK exist in your directory, issue the command 

;:J-IF ADD.TSKr*/LI <CR> 

As the example illustrates, the file specification always precedes the 
switch. 

The command requests PIP to display a directory listing of all versions of 
the file called ADD.TSK. The PIP request refers to all versions of the file 
because you entered an asterisk (*) in the version number field of the file 
specification. The asterisk, called a wildcard, stands for "all"; it can be 
placed in any field of the file specification, other than the device field. 
For example, 

ADD.*?* 



3-7 



The Files 



I 



means all types and all versions of the file name ADD. Since all the files in ^, 

the directory listed above are named ADD, the command m\ 

>pip Ariii.*;*/Li <CR> 
has the same effect as 

>PIP /LI <CR> 
which lists out all files in the directory. 

3.2.3 Deleting Files 

PIP includes two switches for deleting files: 

/DE Delete the one or more files specified. 

/PU Purge (delete) all but the highest version(s) of the one or 
more files specified. 

Once you know what files are listed in your UFD, you can decide which 
files you want to delete. Considering the hst shown in Figure 3-1 , suppose 
you decide to retain only the highest version of each file. You conse- 
quently need to delete the following files: 

ADD.OBJ;! 
ADD.TSK;! 
ADD.TSK;2 

To delete these files by means of the /DE switch, issue the command 

>P1P ADD . OBJ f 1 f ADD . TSK r 1 , ADD , TSK ! 2/DE <CR> 

This example demonstrates how to enter a list of specifications; a comma 
separates one specification from the next, and the switch follows the last 
specification (PIP filespec,..., filespec/sw). 

Note that the /DE option requires either an explicit version number or a 
wildcard in the version field. However, the wildcard (*) feature is inappro- 
priate when the UFD lists other files with the same name, but with dif- 
ferent types and versions that you want to retain. In this instance, it is 
necessary to specify each file to be deleted. 

When you want to eliminate all but the highest version of one or more 
files, the /PU switch is more efficient than /DE. The following command 
has the same effect as the above use of the /DE switch (in the context of 
the UFD listed in Figure 3-1): 

>PIP ADD.*/PU <CR> 



I 
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/PU does not affect files that have only one version listed within the UFD. 
Note that the purged file specification does not include a version field. 

>F'IP /LI <CR> 

DIRECTORY DBOI C301 »3143 
25-MAY-77 14:56 



ADn,0BJf2 


2. 


25-MAY-77 


14:31 


ADD. MAP fl 


4. 


25-MAY-77 


14:32 


ADD. STB ?1 


3. 


25-MAY-77 


14:32 


ADD.FTNf 1 


1. 


20-MAY-77 


15:26 


ADD.TSKJ3 


29. 


C 25-MA7-77 


14:33 



TOTAL OF 39. /49. BLOCKS IN 5. FILES 



As the listing shows, the directory now contains only the highest version 
of each file. 

3.2.4 Copying Files 

Copying files is PIP's default function; that is, PIP assumes the copy 
function when you do not specify a switch. For example, the following 
command copies file ADD.MAP from your area on SY: to your area 
on another disk: 

>F-iP dk:=add.«ap <cr> 

The command includes the call to PIP, followed by a file expression 
(see Section 2.2) in the form 

outfile=infile 

where infile is the file to be copied and outfile is the destination of the 
new copy. When outfile omits the UFD, file name, type, and/or version, 
PIP defaults the UFD, filename, type, and version to the equivalent fields 
in the infile. 

Any volume that you reference in a file specification must be allocated 
to you (multiuser protection systems only) and mounted. If the volume 
specified or implied in either infile or outfile is not mounted, PIP returns 
the message 

PIP — DEVICE NOT MOUNTED 

In addition, before you can copy a file to a directory on another volume, 
the directory must exist. In a multiuser protection system, your directory 
on SY: is the only UFD automatically created for you; and in a non- 
multiuser system, no UFDs are automafically created. If the output disk 
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specified in the above example does not contain a UFD corresponding 
to your UIC, PIP returns the message 

PIP — CANNOT FIND DIRECTORY FILE 

Device allocation, mounting, and the creation of UFDs are all MCR 
functions, effected respectively by the following commands: 

• ALLOCATE 

• MOUNT 

• UFD 

See the RSX-llM Operator's Procedures Manual for a description of 
these commands. Specifically note the sections on nonprivileged users 
working in a multiuser system. Note, however, that these three commands 
cannot be issued by nonprivileged users if the system does not support 
multiuser protection. 

3.2,5 Spooling Files to the Line Printer 

System users often need line printer listings of files; consequently, the 
hne printer is usually in heavy demand. RSX-llM provides an optional 
feature called spooling that allows more efficient, nondisruptive use of the 
line printer. To spool files to the line printer, use the PIP switch /SP. 
For example; 

>PIP ADD.MAP/SP <CR> 

Note that you do not need to specify LP: as the output file. This com- 
mand requests PIP to enter the name ADD.MAP in a queue of files waiting 
to be listed at the printer. The system maintains the queue of names, 
copying each file or group of files to the line printer on a first-queued, 
first-printed basis. 

Find out from the system manager whether or not your system supports 
spooling. If it supports spooling, the system automatically directs certain 
files to the Hne printer (see Requesting a Listing File, Section 2.2). Also 
note that spooling can be generated to delete all files spooled to the 
printer; this feature should therefore be used with care. 

If you issue a command like the one above, and your system does not sup- 
port the spooling option, PIP returns the message 

PIP — FAILED TO SPOOL FILE FOR PRINTING 

If this message appears, you must request a listing in the conventional 
copy format: 

>PIP LP := ADD. MAP -^CR:::- 



c 



€ 



C 
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3.2.6 Renaming FUes 

The PIP switch /RE allows you to rename existing files. For example, 
the command 

>PIP AnnTWO.*;*=ADD.*»*/RE <CR> 

tells PIP to change the file-name field of all types and versions of the 
files named ADD to ADDTWO. Note that you must explicitly specify 
either a number or a wildcard in both version fields when you use the 
/RE switch. The wildcards in the output file specifier indicate that the 
type and version of the renamed files are not to be changed. Your 
directory now looks as follows: 

DIRECTORY DBO J 11301 f 3143 
25-MAY-77 16M3 



ADDTWO. OBJ J 2 


2. 


25-MAY-77 


14J31 


ADDTWO. MAP fl 


4. 


25-MAY-77 


14:32 


ADDTWO. STB fl 


3. 


25-hAY-77 


14532 


ADDTWO. FTN 51 


1. 


20--MAY-77 


15:26 


ADDTW0.TSKJ3 


29. 


C 25~MAY--77 


14:33 



TOTAL OF 39. /49. BLOCKS IN 5. FILES 



Because the renaming function does not transfer data, you cannot specify 
a different device in the output file specification. If you want to rename 
a file as you copy it to another volume, enter the new name in the output 
specification of the copy command hne. For example: 

>PIP DK: ADDTWO.* 5 *=ADD.*f* <CR> 

This command tells PIP to copy aU types and versions of the file named 
ADD, which are stored in your UFD on SY:, to an equivalent UFD on 
the DK disk, unit 0, where they are named ADDTWO. 



3-11 



( 



c 



( 



( 



APPENDIX 
SUMMARY OF EXAMPLE PROGRAM 



The following listing summarizes the development of the FORTRAN 
program ADD and the manipulation of the resultant files. 

>HEL <CR> 

ACCOUNT OR NAME} CHARLES <CR> 

PASSWORD J GREY <CR> 

RSX-llM BL18 MULTI-USER SYSTEM 

GOOD MORNING 

22-MAY-77 li:07 LOGGED ON TERMINAL TT4J 

22-MAY-77 

SYSTEM WILL BE DOWN TODAY FROM 13:00-15:00 FOR 
CORRECTIVE MAINTENANCE 

>EDI ADD.FTN <CR> 
[CREATING NEW FILE3 
INPUT 

TYPE 1 <CR> 

1 FORMAT (' ENTER TWO NUMBERS - M»N') <CR> 
APPE\EPP\CCEPT 2»KfL <CTRL/R> 

ACCEPT 2rKrL <CR> 

2 FORMAT (22\2\I5) <CR> 
PRINT "U 

TYPE 3,K+L <CR> 

3 FORMAT (' THE SUM IS 'fI5) <CR> 
STOP <CR> 

END <CR> 
<CR> 
*EX <CR> 

lexit:i 

>PIP Ti:=ADD.FTN <CR> 

TYPE 1 

1 FORMAT (' ENTER TWO' NUMBERS - MrN') 
ACCEPT 2»K+L 

2 FORMAT (215) 
TYPE 3fK+L 

3 FORMAT (' THE SUM IS ',15) 
STOP 

END 
::EDI ADD.FTN <CR> 
C00009 LINES READ IN] 
CPAGE 13 

*LOCATE ENTER <CR> 

1 FORMAT (' ENTER TWO NUMBERS - M,N') 
*CHANGE/ENTER/TYPE/ <CR> 

1 FORMAT (' TYPE TWO NUMBERS - MrN') 
*NEXT <CR> 
*PRINT <CR> 

ACCEPT 2fK+L 



A-1 



Summary of Example Program 



*LOCATE SUM <CR> 

3 FORMAT (' THE SUM IS 'rI5) 

*CHANGE/SUM/RESULT/ <CR> 

3 FORMAT (' THE RESULT IS '»I5) 

*LOCATE <2I5) <CR> 

i:*E0B*3 

)|eTOP <CR> 

*<CR> 

TYPE 1 
*EXIT <CR> 

c:exit3 

>edi adiuftn <cr> 

c000093 lines read in 

[PAGE 13 

)|tINSERT <CR::- 

C THIS PROGRAM ADDS TWO NUMBERS TOGETHER <CR> 

<CR> 

*LOCATE NUMBERS <CR> 

1 FORMAT <' TYPE TWO NUMBERS - MrN') 

*ADD ! INPUT PROMPT <CR> 

*PRINT <CR> 

1 FORMAT (' TYPE TWO NUMBERS - M>N')!INPUT PROMPT 

*LOCATE RESULT <CR> 

3 FORMAT (' THE RESULT IS '»I5) 

*DELETE <CR> 

*<ESC> 

TYPE 3rK+L 
KtlNSERT <CR> 

3 FORMAT (' THE SUM IS ' r 15) ! DISPLAY RESULT <CR> 

■s:CR> 

*TOP <CR> 
*<CR> 

C THIS PROGRAM ADDS TWO NUMBERS TOGETHER 
*RETYPE C ADD DISPLAYS THE SUM OF TWO NUMBERS <CR:: 
>KLIST <CR> 
C ADD DISPLAYS THE SUM OF TWO NUMBERS 

TYPE 1 

1 FORMAT <' TYPE TWO NUMBERS - M»N')! INPUT PROMPT 
ACCEPT 2»KjL 

2 FORMAT (215) 
TYPE 3jK+L 

3 FORMAT <' THE SUM IS ' r 15) ! DISPLAY RESULT 
STOP 

END 

*EXIT <CR> 

CEXIT3 

>FOR AnDjADD=ADD <CR> 

>TKB AnD,ADD»ADD=ADD 

::-RUN ADD <CR> 

TYPE TWO NUMBERS - MrN 

7,2 <CR> 

THE SUM IS 10 

TT13 -- STOP 

>RUN ADD <CR> 

TYPE TWO NUMBERS - MjN 

522 » 628 <CR> 

THE SUM IS 1150 

TT13 - STOP 

>RUN ADD <CR> 

TYPE TWO NUMBERS ~ M»N 

9,16 <CR> 
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( 



THE SUM IS 
TT13 — STOP 
>PIP <CR> 
PIP>/LI <CR> 



DIRECTORY DBO: C301 ,3143 
25-MAY-77 14:48 



( 



AriD,0BJr2 
ADn.TSKJl 
ADD, MAP? 1 
ADD. STB ;i 
ADD.FTNrl 
ADIi.TSKr3 
ADD.OBJJl 
ADri.TSKr2 



29, 

4. 

3. 

1. 

29, 

2, 

29. 



25-MAY- 
20-MAY- 
25-MAY- 
25-MAY- 
20-MAY- 
25-MAY- 
20-MAY- 
20-MAY- 



77 14:31 
77 14:32 
77 14:32 
77 14:32 
77 15:26 
77 14:33 
77 15:27 
77 15:28 



TOTAL OF 99./112, BLOCKS IN 8, FILES 

PIP> 

PIP><CTRL/Z> 
>PIP ADD,*/PU <CR> 
>PIP /LI <CR> 



( 



( 



DIRECTORY nB0:C301. 3143 
25-MAY-77 14:56 



ADD. OBJ 5 2 
ADD, MAP fl 
ADD, STB J 1 
ADD,FTN»1 
ADD,TSKf3 



4, 
3, 
1. 
29, 



25-MAY-77 14:31 
25-MAY-77 14:32 
25-MAY-77 14:32 
20-MAY-77 15:26 
25-MA7-77 14:33 



TOTAL OF 39. /49. BLOCKS IN 5, FILES 

>PIP ADDTWO.*;)|c=ADD,*r*/RE •=:CR> 
>PIP /LI <CR> 



DIRECTORY DBO: C301 ,3143 
25-MAY-77 16:43 



ADDTU0,0BJ?2 
ADDTW0,MAPJ1 
ADDTW0.STB5 1 
ADDTWCFTNfl 

addtwo,tsk;3 



4, 
3, 
1, 
29. 



25-MAY-77 14:31 
25-MAY-77 14:32 
25-MAY-77 14:32 
20-MAY-77 15:26 
25-MAY-77 14:33 



TOTAL OF 39. /49, BLOCKS IN 5. FILES 
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Access restrictions, 

file, 3-3 
Allocating device, 3-10 
ANS magnetic tape, 2-1 
Appending text string, 2-6, 2-7, 2-9 
Assembling MACRO program, 2-11, 

2-12 
Assembly switches, 2-1 1 
Asterisk convention, 3-7 

Buffer, 

renewing editing, 24, 2-9 
BYE command, 1-9 

Carriage return, 1-3, 1-7 
Changing text string, 2-5,2-9 
Characters, 

deleting, 1-3 
Clearing the terminal, 1-7 
Command, 

BYE, 1-9 

EDI, 2-2 

FOR, 2-8 

HELLO, 1-8 

HELP, 1-9 

MAC, 2-11 

RUN, 2-15 

SET/UIC, 3-3 

TKB, 2-12 
Command format, 

MCR, 1-5 to 1-7 
Command name, 1-5 
Command parameters, 1-6 
Commands, 

basic EDI, 2-9 

editor, 2-3 

issuing MCR, 1-5 to 1-7 

MCR, 1-5 to 1-10 
Compiler switches, 2-10 
Compiling FORTRAN program, 

2-8,2-10 
Copying files, 3-9 
Creating source program, 2-2 
Creating UFD, 3-10 
Current Une, 

displaying (CTRL/R), 14 

printing (EDI), 2-5 



/DE switch, 3-8 
DECtapes, 2-1 
Default prompt, 1-7 
Default system disk, 2-2 
Default types, 2-2 

FOR, 2-10 

TKB, 2-14 
Default UFD, 3-3 

setting, 3-3 
Defaults, 

file specification, 3-5 
Deleting characters, 1-3 
Deleting files, 3-8 
Deleting lines, 

CTRL/U, 1-5 

EDI DELETE command, 2-6, 2-9 
Deleting terminal output, 

CTRL/O, 14 
Deleting text string, 2-6, 2-9 
Device, 

allocating, 3-10 

mounting, 3-10 

pseudo, 3-2 

SY:, 2-15,3-2 
Device name, 3-1 
Directories, 

user file, 3-3 
Directory, 

listing, 3-6 
Disk, 

default system, 2-2 
Disks, 2-1 

Displaying current line, 14 
Displaying file, 2-3 
Displaying lines, 2-7,2-8,2-9 

EDI, 2-2 

EDI commands, 

basic, 2-9 
Edit mode, 2-3 
Editing buffer, 

renewing, 24, 2-9 
Editing source program, 2-4 
Editor, 

text, 2-2 
Editor commands, 2-3,2-9 
Error messages, 1-11 
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File, 2-1 

displaying, 2-3 

input, 2-10 

memory allocation, 2-13, 2-14 

output, 2-10 

symbol definition, 2-13,2-15 

task-image, 2-13 
File access restrictions, 3-3 
File directories, 

user, 3-3 
File expression, 2-8 
File information, 

listing, 3-6,3-7 
File name, 2-2 

File specification defaults, 3-5 
File specifications, 

complete, 3-1 
File type, 2-2 
Files, 

copying, 3-9 

deleting, 3-8 

listing, 3-6,3-7 

manipulating, 3-5 

purging, 3-8,3-9 

renaming, 3-11 

TKB output, 2-13 
FOR command, 2-8 
Format, 

MCR command, 1-5 to 1-7 
FORTRAN program, 

compiling, 2-8, 2-10 

HELLO command, 1-8 
HELP command, 1-9 

Identification code, 

user, 1-8 
Information, 

listing file, 3-6,3-7 
Input file, 2-10 
Input mode, 2-3 
Inserting text string, 2-6 
Interchange program, 

peripheral, 3-5 
Issuing MCR commands, 1-5 to 1-10 

Keywords, 1-6 

/LI switch, 3-6,3-7 

Line, 
displaying current (CTRL/R), 14 
printing current (EDI), 2-5 

TKB command, 2-13 



Line pointer, 2-4 

moving, 24 
Line printer spooler, 2-10, 3-10 
Line terminator, 1-7 
Lines, 

deleting, 1-5,2-6,2-9 

displaying, 2-7, 2-8, 2-9 
Linking object programs, 2-12 
Listing directory, 3-6 
Listing file information, 3-7 
Listing files, 3-6, 3-7 
Listing UFD, 3-6,3-7 
Locating text string, 2-5, 2-9 
Logging off terminal, 1-7,1-9 
Logging onto terminal, 1-7, 1-8, 1-10 

MAC command, 2-1 1 
MACRO program, 

assembling, 2-11 
Magnetic tape, 

ANS, 2-1 
Manipulating files, 3-5 
Mask, 

protecfion, 3-3 
MCR command format, 1-5 to 1-7 
MCR commands, 1-5 

issuing, 1-5 to 1-10 
MCR prompt, 1-7 
Memory allocation file, 2-13,2-14 
Messages, 

error, 1-11 

suppressing system, 1-10 
Monitor console routine, 1-5 
Mounting device, 3-10 
Multiuser protection, 1-7, 3-3 

Name, 
command, 1-5 
device, 3-1 
file, 2-2 

Object program, 2-8 

linking, 2-12 
Obtaining prompt, 1-7 
Options, 

TKB, 2-15 
Output, 

deleting terminal (CTRL/0), 1-4 

stopping terminal (CTRL/S), 1-4 
Output files, 2-10 

TKB, 2-13 
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Parameters, 

command, 1-6 
Password, 1-8 
Peripheral interchange 

prograni, j-j 
PIP, 3-5 

PIP switches, 3-6 
Pointer, 

line, 24 

moving line, 24 
Printing current line (EDI), 2-5 
Privilege violations, 3-3,34 
Program, 

assembling MACRO, 2-11 

compiling FORTRAN, 2-8,2-10 

creating source, 2-2 

editing source, 24 

linking object, 2-12 

object, 2-8 

peripheral interchange, 3-5 

preparing, 2-1 to 2-17 
Prompt, 

default, 1-7 

MCR, 1-7 

obtaining, 1-7 
Protection, 

multiuser, 1-7,3-3 
Protection mask, 3-3 
Pseudo device, 3-2 
/PU switch, 3-8, 3-9 
Purging files, 3-8,3-9 

/RE switch, 3-1 1 

Renaming files, 3-11 

Renewing editing buffer, 24,2-9 

Replacing text string, 2-7, 2-8, 2-9 

Restrictions, 

file access, 3-3 
RUN command, 2-15 
Running task, 2-15 

SET /UIC command, 3-3 
Setting default UFD, 3-3 
Source program, 

creating, 2-2 

editing, 24 
/SP switch, 3-10 
Specification defaults, 

file, 3-5 
Specifications, 

complete file, 3-1 
Spooling, 2-10,3-10 
Stopping terminal output, 14 



String, 

appending text, 2-6,2-7,2-9 

changing text, 2-5, 2-9 

deleting text, 2-6,2-9 

inserting text, 2-6, 2-7, 2-9 

locating text, 2-5,2-9 

replacing text, 2-7, 2-9 
Suppressing system messages, 1-iO 
Switch, 

/DE, 3-8 

/LI, 3-6,3-7 

/PU, 3-8,3-9 

/RE, 3-11 

/SP, 3-10 
Switches, 

assembly, 2-1 1 

compiler, 2-10 

PIP, 3-6 

TKB, 2-15 
SY: device, 2-15,3-2 
Symbol definition file, 2-13,2-15 
System disk, 

default, 2-2 

Tape, 

ANS magnetic, 2-1 
Task, 2-1 

running, 2-15 
Task Builder, 2-12 to 2-15 
Task name, 

temporary, 2-16 
Task-image file, 2-12,2-13 
Temporary task name, 2-16 
Terminal, 

clearing the, 1-7 

logging off, 1-9 

logging onto, 1-7,1-8,1-10 
Terminal output, 

deleting (CTRL/0), 1-4 

stopping (CTRL/S), 14 
Terminator, 

line, 1-7 
Text editor, 2-2 
Text string, 

appending, 2-6,2-7,2-9 

changing, 2-5, 2-9 

deleting, 2-6,2-9 

inserting, 2-6,2-7,2-9 

locating, 2-5,2-9 

replacing, 2-7, 2-9 
TKB, 2-12 

command line, 2-13 

default types, 2-14 

options, 2-15 
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output files, 2-13 
switches, 2-15 
Type, 
file, 2-2 

UFD, 3-3 
creating, 3-10 
default, 3-3 
listing, 3-6,3-7 
setting, 3-3 



UIC, 1-8 

User file directories, 3-3 

User identification code, 1- 

Version number, 34 
Violations, 

privilege, 3-3, 3-4 
Volume, 2-1 

Wildcard, 3-7 
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READER'S COMMENTS 



NOTE: This form is for document comments only. DIGITAL will use comments submitted on this form at the 
company's discretion. Problems with software should be reported on a Software Performance Report 
(SPR) form. If you require a written reply and are eligible to receive one under SPR service, submit 
your comments on an SPR form. 



Did you find errors in this manual? If so, specify by page. 



Did you find this manual understandable, usable, and well-organized? Please make suggestions for improvement. 



Is there sufficient documentation on associated system programs required for use of the software described in this 
manual? If not, what material is missing and where should it be placed? 



S Please indicate the type of user/reader that you most nearly represent. 

01 

D Assembly language programmer 

n Higher-level language programmer 

D Occasional programmer (experienced) 

n User with little programming experience 

D Student programmer 

D Non-programmer interested in computer concepts and capabilities 



Name. 



. Date 



Organization . 

Street 

City 



. State. 



Zip Code 

or 
Country 
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